Getting Started

Install paste python package

You can install the package on pypi: https://pypi.org/project/paste-bio/

[1]:

import time
import pandas as pd
import numpy as np
import torch
import scanpy as sc
import matplotlib.pyplot as plt
import matplotlib.patches as mpatches
from paste3.visualization import plot_slice, stack_slices_pairwise, stack_slices_center
from paste3.paste import pairwise_align, center_align
from paste3.helper import filter_for_common_genes, match_spots_using_spatial_heuristic

Read data and create AnnData object

[2]:

data_dir = "../../../tests/data/input/"


# Assume that the coordinates of slices are named slice_name + "_coor.csv"
def load_slices(data_dir, slice_names=["slice1", "slice2", "slice3", "slice4"]):
    slices = []
    for slice_name in slice_names:
        slice_i = sc.read_csv(data_dir + slice_name + ".csv")
        slice_i_coor = np.genfromtxt(data_dir + slice_name + "_coor.csv", delimiter=",")
        slice_i.obsm["spatial"] = slice_i_coor
        # Preprocess slices
        sc.pp.filter_genes(slice_i, min_counts=15)
        sc.pp.filter_cells(slice_i, min_counts=100)
        slices.append(slice_i)
    return slices


slices = load_slices(data_dir)
slice1, slice2, slice3, slice4 = slices

Each AnnData object consists of a gene expression matrx and spatial coordinate matrix.

[3]:

slice1.X

[3]:

array([[12.,  0.,  6., ...,  0.,  0.,  0.],
       [ 7.,  0.,  1., ...,  1.,  0.,  0.],
       [15.,  1.,  4., ...,  0.,  0.,  1.],
       ...,
       [ 0.,  0.,  0., ...,  0.,  0.,  0.],
       [ 1.,  0.,  0., ...,  0.,  0.,  0.],
       [ 5.,  0.,  1., ...,  1.,  0.,  0.]], dtype=float32)

[4]:

slice1.obsm["spatial"][0:5, :]

[4]:

array([[13.064,  6.086],
       [12.116,  7.015],
       [13.945,  6.999],
       [12.987,  7.011],
       [15.011,  7.984]])

Note, you can choose to label the spots however you want. In this case, we use the default coordinates.

[5]:

slice1.obs

[5]:

	n_counts
13.064x6.086	2181.0
12.116x7.015	2295.0
13.945x6.999	3375.0
12.987x7.011	2935.0
15.011x7.984	2964.0
...	...
21.953x24.847	541.0
20.98x24.963	860.0
20.063x24.964	508.0
19.007x25.045	626.0
21.957x25.871	2515.0

254 rows × 1 columns

[6]:

slice1.var

[6]:

	n_counts
GAPDH	2233.0
UBE2G2	78.0
MAPKAPK2	255.0
NDUFA7	96.0
ASNA1	172.0
...	...
DIP2C	31.0
LYPLA2	19.0
RGP1	24.0
BPGM	17.0
HPS6	16.0

7998 rows × 1 columns

We can visualize the spatial coordinates of our slices using plot_slices.

[7]:

slice_colors = ["#e41a1c", "#377eb8", "#4daf4a", "#984ea3"]

fig, axs = plt.subplots(2, 2, figsize=(7, 7))
plot_slice(slice1, slice_colors[0], ax=axs[0, 0])
plot_slice(slice2, slice_colors[1], ax=axs[0, 1])
plot_slice(slice3, slice_colors[2], ax=axs[1, 0])
plot_slice(slice4, slice_colors[3], ax=axs[1, 1])
plt.show()

../_images/notebooks_paste_tutorial_13_0.png

We can also plot using Scanpy’s spatial plotting function.

[8]:

sc.pl.spatial(slice1, color="n_counts", spot_size=1)

../_images/notebooks_paste_tutorial_15_0.png

Pairwise Alignment

Run PASTE `pairwise_align`.

[9]:

start = time.time()

pi12 = pairwise_align(slice1, slice2)
pi23 = pairwise_align(slice2, slice3)
pi34 = pairwise_align(slice3, slice4)

print("Runtime: " + str(time.time() - start))

(INFO) (paste.py) (24-Oct-24 13:51:36) GPU is not available, resorting to torch CPU.
(INFO) (paste.py) (24-Oct-24 13:51:36) GPU is not available, resorting to torch CPU.
(INFO) (paste.py) (24-Oct-24 13:51:36) GPU is not available, resorting to torch CPU.
Runtime: 0.4010148048400879

[10]:

pd.DataFrame(pi12.cpu().numpy())

[10]:

	0	1	2	3	4	5	6	7	8	9	...	240	241	242	243	244	245	246	247	248	249
0	0.003937	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
1	0.000063	0.003874	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
2	0.000000	0.000000	0.000000	0.0	0.0	0.003937	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
3	0.000000	0.000126	0.003811	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
4	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.003874	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
249	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	3.937008e-03	0.000000	0.000000
250	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	6.299213e-05	0.003874	0.000000
251	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000126	0.003811	0.0	0.0	0.0	3.035766e-17	0.000000	0.000000
252	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.003748	0.000000	0.000189	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
253	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.003937

254 rows × 250 columns

Sequential pairwise slice alignment plots

[11]:

pis = [pi12, pi23, pi34]
slices = [slice1, slice2, slice3, slice4]

new_slices = stack_slices_pairwise(slices, pis)

Now that we’ve aligned the spatial coordinates, we can plot them all on the same coordinate system.

[12]:

slice_colors = ["#e41a1c", "#377eb8", "#4daf4a", "#984ea3"]

plt.figure(figsize=(7, 7))
for i in range(len(new_slices)):
    plot_slice(new_slices[i], slice_colors[i], s=400)
plt.legend(
    handles=[
        mpatches.Patch(color=slice_colors[0], label="1"),
        mpatches.Patch(color=slice_colors[1], label="2"),
        mpatches.Patch(color=slice_colors[2], label="3"),
        mpatches.Patch(color=slice_colors[3], label="4"),
    ]
)
plt.gca().invert_yaxis()
plt.axis("off")
plt.show()

../_images/notebooks_paste_tutorial_23_0.png

We can also plot pairwise layers together.

[13]:

slice_colors = ["#e41a1c", "#377eb8", "#4daf4a", "#984ea3"]

fig, axs = plt.subplots(2, 2, figsize=(7, 7))
plot_slice(new_slices[0], slice_colors[0], ax=axs[0, 0])
plot_slice(new_slices[1], slice_colors[1], ax=axs[0, 0])
plot_slice(new_slices[1], slice_colors[1], ax=axs[0, 1])
plot_slice(new_slices[2], slice_colors[2], ax=axs[0, 1])
plot_slice(new_slices[2], slice_colors[2], ax=axs[1, 0])
plot_slice(new_slices[3], slice_colors[3], ax=axs[1, 0])
fig.delaxes(axs[1, 1])
plt.show()

../_images/notebooks_paste_tutorial_25_0.png

We can also plot the slices in 3-D.

[14]:

import plotly.express as px
import plotly.io as pio

pio.renderers.default = "notebook"

slices_colors = ["#e41a1c", "#377eb8", "#4daf4a", "#984ea3"]

# scale the distance between layers
z_scale = 2

values = []
for i, L in enumerate(new_slices):
    for x, y in L.obsm["spatial"]:
        values.append([x, y, i * z_scale, str(i)])
df = pd.DataFrame(values, columns=["x", "y", "z", "slice"])
fig = px.scatter_3d(
    df, x="x", y="y", z="z", color="slice", color_discrete_sequence=slice_colors
)
fig.update_layout(scene_aspectmode="data")
fig.show()

Center Alignment

First, we will read in and preprocess the data (if you ran pairwise_align above, it will be altered).

[15]:

slices = load_slices(data_dir)
slice1, slice2, slice3, slice4 = slices

Run PASTE `center_align`.

[16]:

slices = [slice1, slice2, slice3, slice4]
initial_slice = slice1.copy()
lmbda = len(slices) * [1 / len(slices)]

Now, for center alignment, we can provide initial mappings between the center and original slices to PASTE to improve the algorithm. However, note this is optional.

[17]:

filter_for_common_genes(slices)

b = []
for i in range(len(slices)):
    b.append(
        torch.Tensor(
            match_spots_using_spatial_heuristic(slices[0].X, slices[i].X)
        ).double()
    )

Filtered all slices for common genes. There are 6397 common genes.

[18]:

start = time.time()

center_slice, pis = center_align(
    initial_slice, slices, lmbda, random_seed=5, pis_init=b
)

print("Runtime: " + str(time.time() - start))

(INFO) (paste.py) (24-Oct-24 13:51:47) GPU is not available, resorting to torch CPU.
Filtered all slices for common genes. There are 6397 common genes.

/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/sklearn/decomposition/_nmf.py:1759: ConvergenceWarning:

Maximum number of iterations 200 reached. Increase it to improve convergence.

Iteration: 0
Solving Pairwise Slice Alignment Problem.
Solving Center Mapping NMF Problem.

/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/sklearn/decomposition/_nmf.py:1759: ConvergenceWarning:

Maximum number of iterations 200 reached. Increase it to improve convergence.

Objective  -13.865903709734415
Difference: 13.865903709734415

Iteration: 1
Solving Pairwise Slice Alignment Problem.
Solving Center Mapping NMF Problem.

/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/sklearn/decomposition/_nmf.py:1759: ConvergenceWarning:

Maximum number of iterations 200 reached. Increase it to improve convergence.

Objective  1.3829621951358517
Difference: 15.248865904870266

Iteration: 2
Solving Pairwise Slice Alignment Problem.
Solving Center Mapping NMF Problem.

/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/sklearn/decomposition/_nmf.py:1759: ConvergenceWarning:

Maximum number of iterations 200 reached. Increase it to improve convergence.

Objective  1.3880932085439706
Difference: 0.005131013408118834

Iteration: 3
Solving Pairwise Slice Alignment Problem.
Solving Center Mapping NMF Problem.

/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/sklearn/decomposition/_nmf.py:1759: ConvergenceWarning:

Maximum number of iterations 200 reached. Increase it to improve convergence.

Objective  1.391523210587665
Difference: 0.003430002043694369

Iteration: 4
Solving Pairwise Slice Alignment Problem.
Solving Center Mapping NMF Problem.

/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/sklearn/decomposition/_nmf.py:1759: ConvergenceWarning:

Maximum number of iterations 200 reached. Increase it to improve convergence.

Objective  1.3930712377027514
Difference: 0.0015480271150865033

Iteration: 5
Solving Pairwise Slice Alignment Problem.
Solving Center Mapping NMF Problem.

/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/sklearn/decomposition/_nmf.py:1759: ConvergenceWarning:

Maximum number of iterations 200 reached. Increase it to improve convergence.

Objective  1.3952504860026191
Difference: 0.0021792482998677087

Iteration: 6
Solving Pairwise Slice Alignment Problem.
Solving Center Mapping NMF Problem.
Objective  1.3953790546398297
Difference: 0.00012856863721055767

Runtime: 23.24843692779541

/opt/hostedtoolcache/Python/3.12.7/x64/lib/python3.12/site-packages/sklearn/decomposition/_nmf.py:1759: ConvergenceWarning:

Maximum number of iterations 200 reached. Increase it to improve convergence.

Again, we can run center align without providing intial mappings below.

[19]:

# center_slice, pis = paste.center_align(initial_slice, slices, lmbda, random_seed = 5)

center_slice returns an AnnData object that also includes the low dimensional representation of our inferred center slice.

[20]:

center_slice.uns["paste_W"]

[20]:

array([[2.56406093e-02, 1.17735607e+00, 1.45992052e-01, ...,
        1.67005417e-02, 8.65816825e-03, 1.64249357e-02],
       [1.93239958e-03, 3.38372964e-01, 1.80787142e-01, ...,
        1.61882816e-02, 1.01921082e-03, 4.46527741e-02],
       [4.19665776e-01, 1.88694807e-01, 2.90303299e-02, ...,
        4.75023417e-02, 1.62389942e-02, 1.17923347e-01],
       ...,
       [2.91596137e-02, 8.19205067e-03, 1.07181457e-01, ...,
        4.61294221e-04, 4.20524970e-04, 2.33305743e-01],
       [4.31159614e-02, 3.82986845e-02, 1.78688011e-01, ...,
        9.82425940e-03, 3.23265908e-03, 2.58807000e-01],
       [1.83314287e-01, 1.68948944e-05, 2.22536847e-02, ...,
        1.16837125e-05, 4.58040722e-03, 9.97049974e-02]])

[21]:

center_slice.uns["paste_H"]

[21]:

array([[9.00595607e-01, 1.28095198e-01, 7.99820095e-02, ...,
        5.45671921e-03, 4.42535702e-02, 2.77099831e-02],
       [1.84556879e+00, 1.12907519e-01, 3.19053467e-01, ...,
        1.01912359e-01, 1.03440812e-01, 3.08299141e-02],
       [1.93982112e+00, 1.42403635e-01, 1.30713055e-01, ...,
        7.35120043e-02, 3.50568629e-02, 2.86018512e-02],
       ...,
       [3.05294214e+00, 1.88580787e-01, 3.20976584e-01, ...,
        2.51081654e-02, 5.00735520e-06, 1.10129733e-02],
       [9.20159439e-01, 1.65184158e-01, 1.04867309e-01, ...,
        1.26153756e-02, 1.25054025e-02, 2.44712738e-02],
       [5.73756511e+00, 7.43537991e-04, 3.13147992e-01, ...,
        6.80617618e-06, 3.99149859e-02, 2.55630212e-13]])

Center slice alignment plots

Next, we can use the outputs of center_align to align the slices.

[22]:

center, new_slices = stack_slices_center(center_slice, slices, pis)

Now that we’ve aligned the spatial coordinates, we can plot them all on the same coordinate system. Note the center slice is not plotted.

[23]:

center_color = "orange"
slices_colors = ["#e41a1c", "#377eb8", "#4daf4a", "#984ea3"]

plt.figure(figsize=(7, 7))
plot_slice(center, center_color, s=400)
for i in range(len(new_slices)):
    plot_slice(new_slices[i], slices_colors[i], s=400)

plt.legend(
    handles=[
        mpatches.Patch(color=slices_colors[0], label="1"),
        mpatches.Patch(color=slices_colors[1], label="2"),
        mpatches.Patch(color=slices_colors[2], label="3"),
        mpatches.Patch(color=slices_colors[3], label="4"),
    ]
)
plt.gca().invert_yaxis()
plt.axis("off")
plt.show()

../_images/notebooks_paste_tutorial_45_0.png

Next, we plot each slice compared to the center.

Note that since we used slice1 as the coordinates for the center slice, they remain the same, and thus we cannot see both in our plots below.

[24]:

center_color = "orange"
slice_colors = ["#e41a1c", "#377eb8", "#4daf4a", "#984ea3"]

fig, axs = plt.subplots(2, 2, figsize=(7, 7))
plot_slice(center, center_color, ax=axs[0, 0])
plot_slice(new_slices[0], slice_colors[0], ax=axs[0, 0])

plot_slice(center, center_color, ax=axs[0, 1])
plot_slice(new_slices[1], slice_colors[1], ax=axs[0, 1])

plot_slice(center, center_color, ax=axs[1, 0])
plot_slice(new_slices[2], slice_colors[2], ax=axs[1, 0])

plot_slice(center, center_color, ax=axs[1, 1])
plot_slice(new_slices[3], slice_colors[3], ax=axs[1, 1])
plt.show()

../_images/notebooks_paste_tutorial_48_0.png

Gpu Implementation

POT allows us to write backend agnostic code, allowing us to use Numpy, Pytorch, etc to calculate our computations (https://pythonot.github.io/gen_modules/ot.backend.html).

We have updated our code to include gpu support for Pytorch.

First, you want to make sure you have torch installed. One way to check is by running:

[25]:

import ot

ot.backend.get_backend_list()

[25]:

[<ot.backend.NumpyBackend at 0x7f33f34df650>,
 <ot.backend.TorchBackend at 0x7f33fcbaa900>]

By default, you should have ot.backend.NumpyBackend(). To use our gpu, make sure you have ot.backend.TorchBackend().

If not, install torch: https://pytorch.org/

Note: From our tests, ot.backend.TorchBackend() is still faster than ot.backend.NumpyBackend() even if you ONLY use cpu, so we recommend trying it if you would like to speed up your calculations.

Now, assuming you have torch installed, we check to make sure you have access to gpu. PASTE automatically does this check for you, but it is still helpful to know if you want to debug why you can’t seem to access your gpu.

[26]:

import torch

torch.cuda.is_available()

[26]:

False

Running PASTE with gpu

Note: Since the breast dataset is small, cpu may actually be faster than gpu in this particular case. For larger datasets, you will see a greater improvement in gpu vs cpu.

First, we read in our data.

[27]:

data_dir = "../../../tests/data/input/"


# Assume that the coordinates of slices are named slice_name + "_coor.csv"
def load_slices(data_dir, slice_names=["slice1", "slice2", "slice3", "slice4"]):
    slices = []
    for slice_name in slice_names:
        slice_i = sc.read_csv(data_dir + slice_name + ".csv")
        slice_i_coor = np.genfromtxt(data_dir + slice_name + "_coor.csv", delimiter=",")
        slice_i.obsm["spatial"] = slice_i_coor
        # Preprocess slices
        sc.pp.filter_genes(slice_i, min_counts=15)
        sc.pp.filter_cells(slice_i, min_counts=100)
        slices.append(slice_i)
    return slices


slices = load_slices(data_dir)
slice1, slice2, slice3, slice4 = slices

Next, running with gpu is as easy as setting two parameters in our function.

[28]:

start = time.time()

pi12 = pairwise_align(slice1, slice2, backend=ot.backend.TorchBackend(), use_gpu=True)
pi23 = pairwise_align(slice2, slice3, backend=ot.backend.TorchBackend(), use_gpu=True)
pi34 = pairwise_align(slice3, slice4, backend=ot.backend.TorchBackend(), use_gpu=True)

print("Runtime: " + str(time.time() - start))

(INFO) (paste.py) (24-Oct-24 13:52:12) GPU is not available, resorting to torch CPU.
(INFO) (paste.py) (24-Oct-24 13:52:12) GPU is not available, resorting to torch CPU.
(INFO) (paste.py) (24-Oct-24 13:52:12) GPU is not available, resorting to torch CPU.
Runtime: 0.37168264389038086

[29]:

pd.DataFrame(pi12.cpu().numpy())

[29]:

	0	1	2	3	4	5	6	7	8	9	...	240	241	242	243	244	245	246	247	248	249
0	0.003937	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
1	0.000063	0.003874	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
2	0.000000	0.000000	0.000000	0.0	0.0	0.003937	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
3	0.000000	0.000126	0.003811	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
4	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.003874	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
249	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	3.937008e-03	0.000000	0.000000
250	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	6.299213e-05	0.003874	0.000000
251	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000126	0.003811	0.0	0.0	0.0	3.035766e-17	0.000000	0.000000
252	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.003748	0.000000	0.000189	0.0	0.0	0.0	0.000000e+00	0.000000	0.000000
253	0.000000	0.000000	0.000000	0.0	0.0	0.000000	0.000000	0.0	0.0	0.0	...	0.0	0.000000	0.000000	0.000000	0.0	0.0	0.0	0.000000e+00	0.000000	0.003937